<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<title>Dialog API 1.0</title>
<meta http-equiv="Content-Type" Content="text/html; charset=utf-8">
<link rel="stylesheet" type="text/css" href="../../styles/styles.css">
<script language="JavaScript" src='../links.js' type="text/javascript"></script>
</head>

<body>

<h1>Dialog API 1.0</h1>
<div class=navbar>
<a href="../index.html">main</a>
</div>


<p class=note><img src="../../images/note.gif" alt="Attention!" width="10" height="10"> Attention!</p>
<UL class=note><LI>
All Dialog API details are written with taking named unions of the
<a href="structures/fardialogitem.html">FarDialogItem</a> structure into account. For more details
see the description of <a href="../defs/_far_no_nameless_unions.html">_FAR_NO_NAMELESS_UNIONS</a>.
</LI></UL>

<div class=shortdescr>
<p>
Dialog API represents an individual API beginning from FAR Manager version 1.70. What's in it for
plugin developers? The main thing is higher control over the created dialog.
<p>There're two different dialog types:<ul>
<li>
Dialogs of so-called "About" style (FAR version 1.65 and below)
<li>
Extended style dialogs - those using the dialog callback function.
</ul>
<p>
Regardless of the style used, dialog manager v1.0 supports only so-called <b>Modal Dialogs</b>. This
dialog represents a window which disables user interaction with any FAR Manager object outside the
boundaries of the dialog. The modal dialog cuts off all keyboard/mouse events sent to other FAR
Manager objects.
</div>

<h3>"About" style</h3>
<div class=descr>
It's simple - UNCONTROLLABLE DIALOGS! Dialogs of this type are created with either
<a href="dialog.html">Dialog</a> or <a href="dialogex.html">DialogEx</a> function call with the
<dfn>DlgProc</dfn> parameter set to NULL.
<p>This style defines the following dialog behavior:
<ul>
<li>any changes in control element state become known to the plugin only after dialog is closed;
<li>dialog is closed when user presses one of the following keys: <code>Esc</code>,
<code>Ctrl-Enter</code>, <code>Enter</code> (pressing <code>Enter</code> closes the dialog
regardless of which control element has the focus, with the exception of edit boxes with
<a href="flags/dif_editor.html">DIF_EDITOR</a> flag set), or clicks a mouse button beyond the
dialog bounds.
<li>
This style is intended for simple dialogs.
</ul>
</div>

<h3>"Extended" style</h3>
<div class=descr>
This is the most interesting style. Plugin has ultimate control over the dialog.
<ul>
<li>dialog has its own callback function which reacts to a lot of messages sent by the Dialog
 Manager;
<li>the callback function communicates with the Dialog Manager by sending
 <a href="dmsg/index.html">messages</a> with the <a href="senddlgmessage.html">SendDlgMessage</a> function;
<li>the callback function can delegate control to the Dialog Manager with the
 <a href="defdlgproc.html">DefDlgProc</a> function;
<li>when user tries to interact with inaccessible FAR Manager objects, clicking mouse buttons
 outside the dialog, the Dialog Manager warns him/her with beeps.
<li>the plugin is in control of the dialog session ending.
<li>this style is intended for dialogs implementing complex user interaction logic.
</ul>
If one simply delegates control to the kernel in a dialog callback function with the
<a href="defdlgproc.html">DefDlgProc</a> function call, then one gets simple About-styled dialog:
<pre class=code>
// dialog callback function with minimal code
LONG_PTR WINAPI MyDlgProc(HANDLE hDlg,int Msg,int Param1,LONG_PTR Param2)
{
  return Info.DefDlgProc(hDlg,Msg,Param1,Param2);
}
</pre>
</div>

<p>
Choosing dialog style is simple:
<ul>
<li>to create a dialog with one <a href="../service_functions/inputbox.html">InputBox</a> choose
simple About style - the lesser the code the simpler the result, reducing possibility of errors;
<li>to create more complex plugins (game, calculator, querying a database using ODBC, etc.) choose
Extended style as it provides complex logic, dynamic controls, advanced user interaction (on which
may depend sunsequent actions), etc..
</ul>

<p>
Well then, the Dialog API v1.0:
</p>
<div class=descr>
<a href="function.html">Functions</a><br>
<a href="structures/index.html">Structures</a><br>
<a href="defs/index.html">Macros and types</a><br>
<a href="controls/index.html">Dialog elements</a><br>
<a href="flags/index.html">Dialog element flags</a><br>
<a href="dmsg/index.html">Events and Messages</a><br>
<a href="keybfocus.html">Input focus</a><br>
<a href="lists4.html">Working with lists</a><br>
</div>

<p>&nbsp;</p>
<h3>Remarks</h3>
<div class=descr>
To get more familiar with the Dialog API see the <code>dialog.cpp</code> file from
"<a href="http://plugring.farmanager.com/downld/files/reversi.zip">Reversi</a>" plugin sources.
</div>


<div class=see>See also:</div><div class=seecont>
<a href="../exported_functions/index.html">Exported functions</a>,
<a href="../service_functions/index.html">Service functions</A>,
<a href="../structures/index.html">Structures</A>,
<a href="../customapi/index.html">Archive support</A>,
<a href="../addons/index.html">Addons</a>
</div>

</body>
</html>